Cream of the Crop 21

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / bbs / kspftp30.zip / KSP-FTP.DOC < prev next >

Wrap

Text File | 1996-09-01 | 66.3 KB | 1,975 lines

KSP FTP (tm) A FTP Door for Bulletin Board Systems Version 3.0 Copyright (C) 1995-96 All Rights Reserved by KEY SOFTWARE PRODUCTS 40 Atherton Court Redwood City, California 94061 BBS/FAX: 415-364-9847 KSP FTP is a trademark of Key Software Products. PCL4C is a trademark of MarshallSoft Computing. WATTCP is a trademark of Erick Engelke. Power C is a trademark of Mix Software. Lantastic is a trademark of Artisoft, Inc. Novell is a trademark of Novell Corp. Banyan Vines is a trademark of Banyan Inc. DESQview is a trademark of Quarterdeck Office Systems. TABLE OF CONTENTS CHAPTER 1 - INTRODUCTION ........................... 1 1.1 Compatibility with BBS Software ............... 1 1.2 Hardware Requirements ....................... 2 1.3 Software Requirements ....................... 2 1.4 Other KSP Software ........................... 2 1.4.1 KSP Telnet ............................. 3 1.4.2 KSP SLIP ............................... 3 1.4.3 KSP Mail ............................... 3 1.4.4 KSP HOST ............................... 3 1.4.5 So Many CD's ............................ 3 CHAPTER 2 - INSTALLATION ........................... 4 2.1 Packet Driver Shims for Novell ................. 4 2.2 Packet Driver Shim for Novell w/Token-RingSNAP .. 5 2.3 Packet Driver Shims for Lantastic .............. 5 2.3.1 Changes to CONFIG.SYS ................... 5 2.3.2 Changes to PROTOCOL.INI ................. 6 2.4 Packet Driver Shims for Banyan Vines ............ 7 2.5 Other Things to Configure ..................... 7 CHAPTER 3 - THE WATTCP CONFIGURATION FILE ............. 8 3.1 Multiple Nodes and the "include" Directive ...... 9 3.2 Using a BOOTP Server .......................... 9 3.3 Manual Configuration ........................ 9 3.3.1 The PC's Host Name ....................... 10 3.3.2 The PC's Domain Name ..................... 10 3.3.3 The PC's IP Address ...................... 10 3.3.4 The Name Server's IP Address .............. 11 3.3.5 The Router's IP Address .................. 11 3.3.6 The PC's Network Mask .................... 11 3.4 TCP/IP Parameters (optional) ................. 11 3.4.1 DNS Search Mode ......................... 12 3.4.2 Timeouts .............................. 13 3.4.3 Maximum Segment Size (MSS) ............... 13 3.5 FTP Operating Parameters ..................... 13 3.5.1 Dynamic Parameters ..................... 14 3.5.2 Retrieving Hostname of Remote Server ...... 14 3.5.3 Blocking Access to Certain Sites .......... 15 3.5.4 Allowing Access to a Limited Set of Sites .... 15 3.5.5 Session Time Limit ...................... 15 3.5.6 Session Reserve Time .................... 15 3.5.7 Inactivity Limit ....................... 16 3.5.8 Minimum Baud Rate ....................... 16 3.5.9 Operating Hours ........................ 16 3.5.10 User Session Logging ................... 17 3.5.11 Non-Standard Port/Fossil Break Detect ... 17 3.5.12 Adding External Protocols .............. 17 3.5.13 Controlling Disk Space Usage ............ 19 TABLE OF CONTENTS 3.5.14 Limiting User Download Bytes ............ 19 3.5.15 Updating BBS Download Bytes ............. 20 3.5.16 Silencing the BBS console bell ........... 20 3.5.17 Disabling the Local Screen .............. 20 CHAPTER 4 - INSTALLING THE FTP DOOR COMMAND ............ 22 4.1 Command Line Parameters ...................... 22 4.1.1 The /SCRIPT Parameter ................... 23 4.1.2 The /MAXMINS Parameter .................. 23 4.1.3 The /CONFIG Parameter ................... 23 CHAPTER 5 - INSTALLING YOUR ACCESS KEY ................ 25 CHAPTER 6 - SELECTING A SERIAL COMMUNICATION PROTOCOL .. 26 6.1 Internal Protocols .......................... 26 6.1.1 Internal Xmodem and Ymodem Protocols ...... 26 6.1.2 Internal 1K-Xmodem/G and Ymodem/G Protocols 26 6.1.3 Internal Zmodem Protocol ................ 27 6.2 External Protocols .......................... 27 6.3 Recommendations ............................ 27 APPENDIX 1 - HOW TO REACH US .......................... 29 APPENDIX 2 - GETTING UPDATES VIA THE INTERNET .......... 30 APPENDIX 3 - LEGAL STUFF ............................ 31 Sep 01, 1996 KSP FTP (tm) v3.0 1 CHAPTER 1 - INTRODUCTION KSP FTP is a BBS door that implements the familiar FTP client program that allows users to transfer files to/from remote computers over a TCP/IP network. If your BBS is connected to the Internet, KSP FTP lets your BBS callers transfer files to and from remote host machines anywhere in the world for the cost of a phone call to your BBS! During file transfers, data between the BBS and the remote host is transmitted using the TCP/IP protocol, while data between the BBS and the user is transmitted using a serial communication protocol such as X/Y/Zmodem. Both internal and external serial communications protocols are supported; internal protocols include Xmodem-Cksm, Xmodem-CRC, 1K-Xmodem, 1K-Xmodem/G, Ymodem, Ymodem/G, and Zmodem. KSP FTP meets the following BBS-specific needs: 1. Terminates the BBS session when user's time limit expires. 2. Terminates the BBS session when user hangs up. 3. Terminates when there's no activity for a sysop-specified period of time. 4. Records the FTP session in a log file. 5. Provide colorized or parameterized messages to user. 6. Restrict users by baud rate. 7. Restrict hours of operation. KSP FTP is shareware. The unlicensed version is fully functional except that it imposes a maximum of five minutes per FTP session. Once licensed, the user is limited only by the amount of time remaining in his BBS session. KSP FTP was implemented using Erick Engelke's Waterloo TCP library, MarshallSoft Computing's PCL4C Personal Communications library and PPL4C Personal Protocol Library, and Mix Software's Power C compiler. 1.1 Compatibility with BBS Software KSP FTP is compatible with any BBS software that can generate a DOOR.SYS file. It works with a BBS configured to use the standard COM1 through COM4 ports, or will automatically detect and use a Fossil driver. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 2 1.2 Hardware Requirements KSP FTP inherently requires that the PC running your BBS software have a physical connection to a TCP/IP network - normally the Internet. Ideally, this connection is by means of an adapter card connected to an Ethernet at your company or school (and then through a "gateway" to the Internet). It is also possible to connect to the Internet through a commercial Internet Access Provier via a dial-up FTP (Serial Line Internet Protocol) connection. This approach requires a second serial port, modem, and telephone line dedicated to this purpose. Information on finding such a provider is available on the KSP BBS. 1.3 Software Requirements KSP FTP runs on top of another piece of software called a "packet driver". The packet driver presents a standard software interface to KSP FTP, regardless of the type of hardware interface that connects the PC to the network. Public domain packet drivers exist for SLIP and PPP links and most Ethernet cards. If your BBS uses a multi-tasking operating system to run multiple nodes on a single PC, then you will need a "packet multiplexer". A packet multiplexer designed specifically for use with KSP network products running under DESQview is available as a freeware package distributed as KSPMUX*.ZIP, where the "*" is the version number. KSP FTP is DESQview "aware" to provide better performance in a multitasking environment. If your PC is connected to a non-TCP/IP proprietary network (such as Novell or Lantastic), you will probably need a packet driver "shim". KSP FTP does NOT require that you purchase a separate TCP/IP package, such as that sold by Novell, Artisoft, or IBM. KSP FTP should happily coexist with any of these packages, however. An assortment of public domain packet drivers, multiplexers, and shims are available on the KSP BBS. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 3 1.4 Other KSP Software Key Software Products offers a number of other products for BBS's: 1.4.1 KSP Telnet A door program that allows callers to connect to remote computers anywhere on the Internet via your BBS. Available now on our BBS. 1.4.2 KSP SLIP A door program that allows callers to run any TCP/IP software from home, including using Mosaic to browse the World Wide Web. Available now on our BBS. 1.4.3 KSP Mail A Multi-Threaded Server for SMTP Mail and NNTP Usenet news. Replaces UUCP, its monthly fees, and slow transfer rates! No more unwanted newsgroups! Instant mail without waiting for scheduled events! Works with any BBS software that presently uses UUCP. Requires a 24hr TCP/IP Internet connection. Can now receive NNTP news feeds! 1.4.4 KSP HOST An inbound Telnet server for MS/DOS Bulletin Board Systems. Every node can answer both telnet and modem calls! Requires a fossil driver on each node, a 24 hour TCP/IP connection to the Internet, and a local area network that supports NetBios such as Novell or Lantastic. 1.4.5 So Many CD's A PCBoard PPE to handle off-line CD-Roms. Seamlessly integrated into PCBoard. Users post requests for off-line files and have then returned as attachments to messages. Configurable message pack-out dates automatically keep your hard disk from getting cluttered. Available now on our BBS. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 4 CHAPTER 2 - INSTALLATION Before installing KSP FTP as a BBS door, you must first install: 1. The network interface hardware. 2. A corresponding packet driver. 3. A packet driver shim (if needed). 4. A packet multiplexer (if needed). Detailed directions for these preliminary steps are available in separate documentation that comes with the corresponding hardware or software. It's most common that multi-node BBS's are interconnected with Ethernet and either Lantastic or Novell. Unfortunately, these two network operating systems were designed using their own proprietary protocols rather than the TCP/IP protocol and their own proprietary software rather than packet drivers to talk to their Ethernet interface cards. However, a piece of software called a packet driver "shim" can be used to let both TCP/IP and their proprietary protocol coexist. 2.1 Packet Driver Shims for Novell Novell's network software is installed in layers as TSRs in the order shown below. These commands are usually found either in the AUTOEXEC.BAT file or in another batch file in a directory typically called C:\NWCLIENT. LSL NE2000 }-- specific to your interface card IPXODI VLM The packet driver shim (ODIPKT) logically sits on top of IPXODI, providing a packet driver interface for software such as KSP FTP: LSL NE2000 +--- Frame Type (0-3) IPXODI | ODIPKT 2 97 }--- The packet driver shim VLM | +----- Packet Vector Interrupt (96-127) (See comment below about hex vs. decimal) The ODIPKT command line parameters may vary according to which Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 5 version of the software you have and how your hardware is configured. The "Frame Type" parameter should correspond to the position of ETHERNET_II among the frame types specified in NET.CFG; zero (0) selects the first frame type, one (1) the second, and so on. The "Packet Vector Interrupt" number should correspond to an unused interrupt vector. Note that older versions of ODIPKT insist that this number be given in decimal (96-127) rather than in hex (0x60-0x7F). The necessary packet driver shim can be downloaded from the Key Software Products BBS as file ODI-SHIM.ZIP. 2.2 Packet Driver Shim for Novell w/Token-RingSNAP Another shim called ODITRPKT exists for Novell that should be used if the underlying network is Token-Ring_SNAP. Installation is similar to ODIPKT as described above, except that the first command line parameter must correspond to the Token-Ring_SNAP frame type in NET.CFG, and starts at "1" rather than "0". This shim can be downloaded from the Key Software Products BBS as file TKN-SHIM.ZIP. 2.3 Packet Driver Shims for Lantastic Using a packet driver shim with Lantastic requires that Lantastic be installed using NDIS (Network Driver Interface Specification) Support. The necessary packet driver shim can be downloaded from the Key Software Products BBS as file DIS-SHIM.ZIP. NDIS allows you to stack multiple protocols on a single adapter. This lets you use multiple protocol drivers (such as LANtastic and TCP/IP) on the same adapter. You can also use NDIS to include third-party adapters that have NDIS drivers in your LANtastic network. Supported adapter types include Ethernet, Token-Ring and ARCNET (R) adapters. The software and documentation necessary to add NDIS support to an existing Lantastic network is available free of charge from Artisoft. Once you have NDIS installed and working with Lantastic, adding the shim is a simple matter of editing PROTOCOL.INI (part of the NDIS support) and CONFIG.SYS. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 6 2.3.1 Changes to CONFIG.SYS With NDIS installed, there will be two device driver lines in your CONFIG.SYS file that look something like the following: DEVICE=C:\LANTASTI\PROTMAN.DOS /I:C:\LANTASTI DEVICE=C:\LANTASTI\AEXNDIS.DOS The file listed in the second line may differ if you are not using Artisoft's interface card; in that case, this file would typically be replaced by a NDIS driver supplied by the card manufacturer. The packet driver shim itself is installed as a third device driver after the first two, as in: DEVICE=C:\LANTASTI\PROTMAN.DOS /I:C:\LANTASTI DEVICE=C:\LANTASTI\AEXNDIS.DOS DEVICE=C:\DRIVERS\DIS_PKT.DOS }--- The packet driver shim 2.3.2 Changes to PROTOCOL.INI The PROTOCOL.INI file is a text file created (usually in the C:\LANTASTI directory) as part of the NDIS installation. Before adding the packet driver shim, it typically looks like the following, but with the "iobase" and "interrupt" parameters changed according to your hardware, or with the entire "[AEXNDIS_NIF]" section replaced if you are not using an Artisoft interface card. [PROTMAN] DRIVERNAME = PROTMAN$ DYNAMIC = YES [AEXNDIS_NIF] DRIVERNAME = AEXNDS$ IOBASE = 0x300 INTERRUPT = 15 Adding the packet driver shim requires adding another section to the PROTOCOL.INI file: [PROTMAN] DRIVERNAME = PROTMAN$ DYNAMIC = YES Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 7 [AEXNDIS_NIF] <---+ DRIVERNAME = AEXNDS$ | IOBASE = 0x300 | INTERRUPT = 15 | These names must match! | [PKTDRV] | DRIVERNAME = PKTDRV$ | BINDINGS = AEXNDIS_NIF <---+ INTVEC = 0x61 CHAINVEC = 0x66 NOVELL = Y Note that the name "AEXNDIS_NIF" must exactly match the spelling used as the title of the previous section, "[AEXNDIS_NIF]"; if you are not using Artisoft interface cards, then both occurences will use some other identifier. The "INTVEC" parameter may be anything from 0x60 to 0x80; you may have to experiment to find an unused interrupt number. 2.4 Packet Driver Shims for Banyan Vines Although Key Software Products has never used it, and thus cannot offer help on its installation, a packet driver shim does exist for Banyan Vines and can be downloaded from the Key Software Products BBS as file BAN-SHIM.ZIP. 2.5 Other Things to Configure Once your network is up and running with a packet driver or a packet driver shim, there are basically two additional steps: 1. Create a WATTCP.CFG configuration file. 2. Configure KSP FTP as a BBS door. As discussed in the next chapter, you may not need a WATTCP.CFG configuration file if you have a BOOTP server. There is a useful program called TCPINFO available on the KSP BBS. If you have no WATTCP.CFG file, it will tell you (after a maximum of 30 seconds) if it was able to automatically configure itself via a BOOTP server. If you have a WATTCP.CFG file, it will determine whether or not you have configured that file properly. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 8 CHAPTER 3 - THE WATTCP CONFIGURATION FILE In order to run, KSP FTP needs to know some information about your network, and tries to find this in a configuration file called WATTCP.CFG. KSP FTP looks in three directories to locate this file. First, it checks for an environment variable called WATTCP.CFG that specifies the directory. Second, it looks in the current (default) directory. Third, if still not found, it looks in the directory that contains the executable (KSP-FTP.EXE). The following example may be helpful for those using the environment variable approach: If you place WATTCP.CFG in your PCB directory, then your AUTOEXEC.BAT file should contain the following command: set WATTCP.CFG=C:\PCB Note that there is no trailing "\" after the directory name! If KSP FTP still can't find the configuration file, it will attempt to automatically configure itself by looking for a "BOOTP" server on your network. (BOOTP is a standard protocol that obtains your "IP address" and other information about your PC from a BOOTP server.) If there is no BOOTP server, or if your PC is not registered in its database, then you must create a configuration file. The configuration file contains one entry per line. A sample configuration file is included in this distribution, but the values MUST be modified to suit your particular environment or else KSP FTP will not work! The syntax of every entry follows the following format: [ directive = [ "data" | data] ] [ # comment | ; comment ] I.e., if a directive is not followed by data, the directive is ignored. Similary, lines without directives are ignored. The directive is NOT case sensitive; the data IS case sensitive. e.g., netmask=255.255.252.0 domainslist=ksp.com ; Our domain Whitespace is normally removed from data; data containing blanks must be surrounded by quotes. An unquoted '#' or ';' marks the beginning of a comment. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 9 3.1 Multiple Nodes and the "include" Directive There must be one WATTCP.CFG file for each BBS node since each node has to be configured with a unique hostname and IP address. All other configuration parameters are usually set at the same values for all nodes. Rather than duplicating these common entries in each WATTCP.CFG file, you can set-up a master configuration file that gets "included" in each of the node-specific files. For example, the node-specific file (WATTCP.CFG) might look like: include=c:\ksp\master.cfg hostname=ourbbspc myip=125.283.210.17 This makes it much easier to make changes since you only have to modify a single file (MASTER.CFG). 3.2 Using a BOOTP Server It's always a good idea to have a configuration file whether or not you use a BOOTP server. If you choose to use a configuration file and want to tell it to use the BOOTP server, this option allows you to specify your the IP address of your BOOTP server. Example: bootp=129.255.0.128 You should specify the domain name manually as described in the next section since the BOOTP protocol doesn't provide that information. Example: domainslist=ksp.com NOTE: An "IP address" is a logical addressing scheme used on TCP/IP networks such as the Internet. Each computer connected to the Internet is assigned a unique IP address. Your local network "guru" or access provider should be able to provide you with those IP addresses you need. IMPORTANT: The IP addresses given in this document are only examples. Do NOT attempt to use them - they will NOT work and your network administrator will probably get VERY upset! Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 10 3.3 Manual Configuration If you don't have a BOOTP server, or if your PC is not registered with a BOOTP server, then you must use the following directives to configure KSP FTP. The values of these parameters are important, and KSP FTP will NOT function properly without the proper values. If you are not familiar with the terminology, or if you are unsure of the proper values, please consult with your network access provider. 3.3.1 The PC's Host Name This is the network name of the PC that runs your BBS (and thus KSP FTP). If your BBS is implemented by a network of PC's, then each PC should have its own unique host name. Example: hostname=bbs Note that the host name does not include the domain name suffix. For example, the hostname of machine '"bbs.ksp.com" is simply "bbs". 3.3.2 The PC's Domain Name This is the network name of the subnet to which your PC (and possibly others) are connected. Example: domainslist=ksp.com Note that the domain name does not include the host name prefix. For example, the domain name of machine '"bbs.ksp.com" is "ksp.com". 3.3.3 The PC's IP Address This is the unique IP address assigned to your PC. Example: my_ip=100.2.37.4 Your local network "guru" or access provider should be able to provide you with the proper IP address of your PC. Note that you should have a different IP address for each node in your BBS. Note: As an alternative, you may also set the IP address using an environment variable, as in: Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 11 set ksp-ip=100.2.37.4 3.3.4 The Name Server's IP Address This is the unique IP address assigned to a network name nerver. You may specify more than on nameserver by using more than one "nameserver" line. Example: nameserver=111.21.108.110 Your local network "guru" or access provider should be able to provide you with the proper IP addresses of appropriate network name servers. 3.3.5 The Router's IP Address This is the unique IP address assigned to the network router. Syntax: gateway = ipaddr [ , subnet [ , subnet_mask ] ] Examples: gateway=129.97.176.1 gateway=129.97.176.2, 129.97.0.0 gateway=129.97.176.2, 129.97.0.0, 255.255.0.0 Usually the (destination) subnet and subnet mask need not be specified, and is used to create a "default". The other forms are used to specify one or more other gatewaya for particular subnets. Your local network "guru" or access provider should be able to provide you with the proper IP address of the network router. 3.3.6 The PC's Network Mask Network masks are used to distinguish destination IP addresses that are on the local subnet from those that are not. This option may not be required, depending on your network topology. Example: netmask=255.255.254.0 Your local network "guru" or access provider should be able to provide you with the proper netmask if needed. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 12 3.4 TCP/IP Parameters (optional) KSP FTP will work without using the following parameters, but they are provided if you wish to change them. 3.4.1 DNS Search Mode A remote hostname (e.g., ralph.ksp.com) is translated into an numeric IP addresse (e.g., 128.16.202.12) by a nameserver. Sometimes, however, users enter hostnames in an abbreviated form. For example, if the local machine (e.g., ruby.ksp.com) was in the same domain (ksp.com) as the remote host (ralph.ksp.com), then perhaps only the remote hostname (ralph) might be given. Short versions like this must be fully expanded (e.g., ralph.ksp.com) before a nameserver can translate them into an IP address. Waterloo TCP/IP solves this by feeding the nameserver with a sequence of constructions formed from the remote hostname and the local machine's domainslist. For a remote hostname given as "a.b" and a domainslist specified in WATTCP.CFG as "c.d", Waterloo TCP/IP would attempt name server lookups first on "a.b.c.d", then on "a.b.d", and then on "a.b". Although this approach is guaranteed to find the appropriate construction, it can waste time performing nameserver lookups on improbable constructions. Consider the sequence of constructions attempted when the remote hostname is "garbo.uwasa.fi" and the local domainslist is "ksp.com": (1) garbo.uwasa.fi.ksp.com -> fails (2) garbo.uwasa.fi.com -> fails (3) garbo.uwasa.fi -> succeeds We've modified Waterloo TCP/IP's search strategy to accelerate name server lookups by adding three optional mode variations, enabled by specifying one of the following WATTCP.CFG configuration parameters: dns_search_mode=map_local_names Abbreviated (local) hostnames that do not contain a period are processed in the normal (Waterloo TCP/IP) manner. Otherwise, hostnames like "garbo.uwasa.fi" are attempted immediately without modification. This is the recommended search mode. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 13 dns_search_mode=fully_specified This mode passes the hostname directly to the nameserver without modification. I.e., it assumes that hostnames are always fully specified by the user without abbreviation. Abbreviated names will not be translated and will be returned by the nameserver as unknown. dns_search_mode=recognized_root Remote hostnames ending in the common domain suffixes (com, edu, gov, mil, net, org, nato, arpa) are attempted immediately without modification. All other hostnames are processed in the normal manner. (Note that this mode is no better than the normal Waterloo TCP/IP strategy with names like "garbo.uwasa.fi".) 3.4.2 Timeouts Most network operations (such as establishing a connection to a remote host) have a maximum time before a timeout error occurs. The default value is 30 seconds; a smaller value is unwise, but larger values may be necessary for particularly bad connections. Example: sockdelay=40 3.4.3 Maximum Segment Size (MSS) The default value of MSS is 1400. If you know what maximum segment size means and know what size you want, you can change it: Example: mss=512 Note: Some Internet access providers configure their dial-up slip and ppp accounts with a very small segment size. You may need to set mss as low as 212 if your Internet connection is through such a connection. 3.5 FTP Operating Parameters The remaining parameters in WATTCP.CFG are operating parameters for KSP FTP that define limits and display files needed while KSP FTP is running. Each follows the format: Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 14 ksp-ftp.<parameter>=<value> where <parameter> and <value> are replaced by appropriate strings. Some operating parameters have counterparts in other members of the KSP family of network application programs. Rather than have multiple entries in the WATTCP.CFG file for each application, such parameters can be specified globally using the format: ksp.<parameter>=<value> This global setting can be overridden for a specific application by using the application-specific form at a subsequent line in WATTCP.CFG. 3.5.1 Dynamic Parameters Configuration file parameters can be made "dynamic". Such parameters are ignored unless activated by an associated command line option: /CONFIG=<number> where "<number>" is a non-zero integer. Dynamic configuration parameters are those that specify a number in square backets as in: ksp-ftp[<number>].<parameter>=<value> The number specified in the configuration parameter must match that in the command line option or else the configuration parameter will be ignored. This also works for dynamic global parameters of the form: ksp[<number>].<parameter>=<value> Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 15 3.5.2 Retrieving Hostname of Remote Server Syntax: ksp-ftp.retrieve_hostnames=<option> Example: ksp-ftp.retrieve_hostnames=enabled Purpose: If enabled, IP addresses of remote ftp servers will be translated into hostnames using the domain name server to provide a reliable identification. Affects both the display and the log files. Comment: Default is disabled. 3.5.3 Blocking Access to Certain Sites Syntax: ksp-ftp.blocked_ip_list=<pathspec> Example: ksp-ftp.blocked_ip_list=c:\ksp\blocked.lst Purpose: Specifies the name of a text file containing a list of blocked IP addresses. No user access to sites on this list will be allowed. 3.5.4 Allowing Access to a Limited Set of Sites Syntax: ksp-ftp.allowed_ip_list=<pathspec> Example: ksp-ftp.allowed_ip_list=c:\ksp\allowed.lst Purpose: Specifies the name of a text file containing a list of IP addresses to which the users are allowed to connect. No user access to sites not on this list will be allowed. 3.5.5 Session Time Limit Syntax: ksp-ftp.max_mins=<number> Example: ksp-ftp.max_mins=30 Purpose: Overrides the time remaining as specified in DOOR.SYS if lower. If omitted, time remaining is that specified by DOOR.SYS. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 16 3.5.6 Session Reserve Time Syntax: ksp-ftp.reserve_mins=<number> Example: ksp-ftp.reserve_mins=3 Purpose: Reduces the time available in the door so that if time runs out, the user still has a small amount of time left on the BBS. This is useful, for example, if your BBS offers a Time Bank so that users can use it to withdraw extra time. 3.5.7 Inactivity Limit Syntax: ksp-ftp.idle_mins=<minutes> Example: ksp-ftp.idle_mins=10 Purpose: Establishes an upper limit on how long the session can remain inactive before it is terminated. If omitted, no inactivity limit is imposed. 3.5.8 Minimum Baud Rate Syntax: ksp-ftp.minbaud=<baudrate>[,<security>] Example: ksp-ftp.minbaud=9600 Example: ksp-ftp.minbaud=9600,100 Purpose: Specifies a minimum baud rate required to use the gateway, and an optional security level required to override the minimum baud rate. If omitted, no minimum baud rate will be required. 3.5.9 Operating Hours Syntax: ksp-ftp.ophours=<hh:mm-hh:mm> Example: ksp-ftp.ophours=21:00-23:00 Purpose: To establish the hours of operation for the gateway; attempts to use the gateway at other times will be disallowed. Times must be specified in 24 hour format. If omitted, the gateway may be used at any time. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 17 Note: If start time is after the stop time, the hours of operation will be interpreted as all but those in the window specified. I.e., setting ophours to 03:20-03:00 will allow operation anytime except 03:00-03:20. 3.5.10 User Session Logging Syntax: ksp-ftp.log_dir=<pathspec> Example: ksp-ftp.log_dir=c:\ksp-ftp Purpose: Specifies the name of a directory where a log of user sessions will be kept. The log files are named KSP-FTP.???, where "???" is the BBS node number. 3.5.11 Non-Standard Port/Fossil Break Detect Syntax: ksp-ftp.serial_port=<adr>,<irq> Example: ksp-ftp.serial_port=3F8,5 Purpose: Used to override serial port and IRQ values implied by "COMx" in DOOR.SYS to support non-standard configurations that are NOT using a fossil driver. Also used WITH a fossil driver to add serial break detection. The port address <adr> must be specified in hex, and the interrupt request line number <irq> must be specified in decimal. 3.5.12 Adding External Protocols Syntax: ksp-ftp.protocol=<letter>,<T|F>,<title> Example: ksp-ftp.protocol=S,T,SEALink Purpose: KSP FTP provides internal support for the Xmodem-Cksm, Xmodem-CRC, 1K-Xmodem, 1K-Xmodem/G, Ymodem, Ymodem/G, and Zmodem protocols. However, additional "external" protocols can be added using this option. (Be sure to read the chapter: "SELECTING A SERIAL COMMUNICATION PROTOCOL"). Internal protocols do not require the use of BBS disk space. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 18 KSP FTP simply reformats the data blocks during a transfer: data transmitted between the BBS and the remote host use FTP's TCP/IP protocol; data transmitted between the BBS and the user use a modem-to-modem protocol. External protocols are implemented by other programs that KSP FTP loads and executes. These programs implement only a modem-to-modem protocol and designed to transfer a file from the disk out over a telephone line or vice-versa. Therefore, when using an external protocol to transfer a file from a remote host to the user, KSP FTP first transfers the entire file from the remote host to the BBS disk using TCP/IP, and then executes the external protocol to transmit the disk file to the user. Uploads to a remote host using an external protocol do the same but in reverse. Each external protocol requires that you create two batch files (explained later) and specify three parameters using the "ksp-ftp.protocol" configuration option: <letter> The letter used to select the protocol. <T|F> "T" if the protocol supports batch transfers. <title> A short identifying phrase. NOTE: The following letters are used to identify internal protocols. If one of these letters is used with this option, the external protocol will replace the corresponding internal protocol. X Xmodem-Cksm C Xmodem-CRC O 1K-Xmodem F 1K-Xmodem/G (download only) Y Ymodem G Ymodem/G (download only) Z Zmodem The two batch files must be located in the same directory as KSP-FTP.EXE, and must be named "KSPFTPR?.BAT" (for receiving a file from the caller) and KSPFTPS?.BAT" (for sending a file to the caller) where the "?" is replaced by the identifying protocol letter. For example, if you use the letter 'K' for the Kermit protocol, the corresponding batch files must be named KSPFTPRK.BAT and KSPFTPSK.BAT. KSP-FTP calls the batch files with four parameters: Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 19 For protocols that do not support batch transfers (such as X-Modem), the first parameter (%1) is simply a filespec. For batch protocols, this parameter is a directory name when receiving. When sending, it is an "at-sign" followed by a filespec; the named file contains a list of other filespecs (one per line) to be sent. The second parameter (%2) is simply a number identifying the serial port, e.g., "1" for COM1. The third (%3) and fourth (%4) parameters are the modem-to-PC (DTE) and carrier (DCE) speeds, respectively. 3.5.13 Controlling Disk Space Usage Syntax: ksp-ftp.mb_external=<megabytes> Example: ksp-ftp.mb_external=10 Purpose: To limit the amount of BBS temporary disk space used by external protocols for file transfers. When a user downloads a file from a remote host using an external protocol, the entire file must first be transferred to a temporary directory on the BBS disk. Since filenames can be requested using wildcards, and since TCP/IP transfer rates approach 1 MB/Sec, it is quite possible that one request could quickly consume all of the BBS disk space. This option prevents that from happening! If this option is specified, the user is informed at the beginning of a external protocol transfer how much disk space may be used for the temporary storage of transferred files. KSP FTP will then monitor how much disk space is actually used and abort the remainder of the request if the limit is exceeded. 3.5.14 Limiting User Download Bytes Syntax: ksp-ftp.kb_limit=BBS | <kilobytes> Example: ksp-ftp.kb_limit=BBS Example: ksp-ftp.kb_limit=2048 Purpose: Limit the number of kilobytes that a user may download. If set to "BBS" as in the first example show above, the limit is that imposed by the user's quota Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 20 controlled by the BBS. If set to a number as in the second example, the number will be the number of kilobytes per FTP session - regardless of how many times the user enters the KSP FTP door while logged into the BBS. 3.5.15 Updating BBS Download Bytes Syntax: ksp-ftp.download_report=<filespec> Example: ksp-ftp.download_report=c:\ksp\download.dat Purpose: Records the number of bytes downloaded during the FTP session in a file whose name (optionally preceded by a drive and directory prefix) is given in the option. If the file already exists, it will be erased before the new information is recorded. The format of the file is extremely simple: one line of text containing the decimal number of bytes that were downloaded. The data recorded in the file can be used to update the user's download allocation. However, since each manufacturer's BBS software is different from the next, it is the sysop's responsibility to write a small program that will take the content of this file and modify the BBS's database. 3.5.16 Silencing the BBS console bell Syntax: ksp-ftp.local_bell=<option> Example: ksp-ftp.local_bell=disabled Purpose: Used to silence the bell on the local BBS console. 3.5.17 Disabling the Local Screen Syntax: ksp-ftp.local_screen=<option> Example: ksp-ftp.local_screen=disabled Purpose: Improves caller's display speed by displaying only prompts and user response on local BBS screen. Eliminates local display of directory or file contents. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 21 Note: Pressing Shift-F1 on the local console of the BBS while a caller is in the door will toggle this setting. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 22 CHAPTER 4 - INSTALLING THE FTP DOOR COMMAND Install KSP FTP as you would any other door program on your BBS. Be sure you setup the BBS to create a DOOR.SYS file for KSP FTP when it runs. (KSP FTP does not need a USER.SYS file.) If you are running multiple BBS nodes accessing a single copy of the file KSP-FTP.EXE, then don't forget to make that file read-only using the DOS ATTRIB command in order to avoid sharing conflicts. Most BBS's use a batch file to run a door. For example, on PCBoard systems you might create a door batch file called "FTP" containing simply: C:\FTP\KSP-FTP BOARD Do NOT change directories within this batch file! KSP FTP expects to find the DOOR.SYS file in whatever is the default directory at the moment it starts to run. That's why the name of the program is preceeded by the name of the directory where it is located. Of course, you must also configure your BBS so it knows where to find this batch file (FTP). 4.1 Command Line Parameters In PCBoard, "%PCBDOOR%" is replaced by the value of the environment variable called "PCBDOOR" which is set to the command line parameters (if any) entered with the door command before exiting to run the door. For example, the PCBoard command: FTP scuacc.scu.edu sets the environment variable "PCBDOOR" to "scuacc.scu.edu" before exiting to run the door. Effectively, the batch file "FTP" becomes: KSP-FTP scuacc.scu.edu BOARD If a host name or IP address is given (as above), KSP FTP will automatically connect to that host at startup, and will return to the BBS as soon as the session with that host is finished (e.g., the user logs out). Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 23 If no command line parameter is given, KSP FTP will prompt the user for the host name when the door starts to run. Unlike the situation described above, when the user logs out of a remote host, control is returned to KSP FTP command mode so that the user can then connect to a different host. A second (third) command line parameter may be provided to specify the login name (password). I.e., the complete command line syntax is: KSP-FTP [<name_or_IP> [<login_name> [login_password]]] where the square brackets "[]" indicate optional parameters. There are three additional command line parameters that may be used: 4.1.1 The /SCRIPT Parameter The /SCRIPT parameter is used to specify a text file to be used as command line input. This feature allows the SysOp to build BBS commands that can (for example) automatically download a set of predetermined files to the caller from some remote ftp site. The syntax is: /SCRIPT=<filespec> where "<filespec>" is replaced by a filename, optionally preceded by a drive letter and/or directory name, as in: /SCRIPT=D:\KSP\SCRIPT.FTP 4.1.2 The /MAXMINS Parameter The /MAXMINS parameter is an alternative to the same parameter that appears in the WATTCP.CFG file. It provides another mechanism for limiting the maximum time a caller is allowed in the door. The syntax is: /MAX_MINS=<minutes> where "<minutes>" is replaced by a number, as in: KSP-FTP scuacc.scu.edu /MAX_MINS=60 Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 24 4.1.3 The /CONFIG Parameter The /CONFIG parameter is used in conjunction with "dynamic" configuration parameters to enable or disable them. For a complete description of this feature, please see the section called "Dynamic Parameters". Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 25 CHAPTER 5 - INSTALLING YOUR ACCESS KEY The unlicensed version of KSP FTP limits each user to a maximum of five minutes per session. To remove this limit, you must purchase an access key and install it as described below; once installed, users will be limited only by their time remaining on the BBS. There are three parameters that must be specified in two environment variables called "KSP-ID" and "KSP-FTP" in order to install your access key; the access key will not be validated if any parameter is missing. The environment variable "KSP-ID" is used to specify your BBS name, as in: set ksp-id=Key Software Products BBS The environment variable "KSP-FTP" is used to specify the number of BBS nodes and your access key separated by a semicolon as in: set ksp-ftp=2;12345678 The access key is derived from the name of your BBS and the number of BBS nodes. The specified key must match the combination of BBS name and nodes. If not, or if you invoke KSP FTP on a node whose node number is greater than indicated, then the caller will be limited to five minutes per session. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 26 CHAPTER 6 - SELECTING A SERIAL COMMUNICATION PROTOCOL There are certain tradeoffs that affect the selection of a serial communications protocol for use with KSP FTP. The choice affects the use of BBS disk space and/or file transfer reliability. After reading this chapter, you may wish to prepare a bulletin for your users to help them understand the issues. 6.1 Internal Protocols Most serial communications protocols are designed with timeout limits of ten seconds or less. However, file transfers over the Internet can sometimes incur delays much greater than this, and affects the reliability of KSP FTP's internal serial communications protocols. 6.1.1 Internal Xmodem and Ymodem Protocols Most Xmodem and Ymodem protocols (except the /G variants) wait for an acknowledgement (ACK) after each block of data that is transmitted. If the ACK does not arrive within a predetermined timeout period, the block is retransmitted. The entire file transfer is aborted after a predetermined number of un-ACK'd retransmissions. Most implementations of Xmodem and Ymodem employ a timeout of around ten seconds, but network delays can sometimes be greater than this and can cause retransmission even though the first attempt was received correctly. These extra retransmissions may unnecessarily cause the file transfer to be aborted. Some communications programs offer "relaxed timing" on Xmodem and Ymodem. This increases the timeout threshold, and may help if long network delays are a problem. 6.1.2 Internal 1K-Xmodem/G and Ymodem/G Protocols The Ymodem/G and 1K-Xmodem/G protocols transmit one block of data after another without waiting for an ACK, depending on error-correcting modems for reliability. They work as long as the receiver can keep up with arriving data; if the receiver is busy doing something else, data is lost and the entire file transfer gets corrupted. For this reason, KSP FTP restricts the use of these two internal protocols to downloads only; uploads Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 27 would fail due to occassional network delays. 6.1.3 Internal Zmodem Protocol Network delays can affect Zmodem uploads the same way they affect Xmodem and Ymodem as discussed above. However, Zmodem downloads are not affected in this manner due to a special feature of the Zmodem protocol. Unlike Xmodem and Ymodem, Zmodem data blocks are variable length. To prevent receiver timeouts, the internal implementation of Zmodem in KSP FTP transmits zero-length data blocks during periods of long network delay, thus resetting the receiver's timeout clock. 6.2 External Protocols Downloading a file using an external protocol is a two-step process. First the file is transferred from the remote host to the BBS using TCP/IP, creating a temporary file on the local disk of the BBS. Then KSP FTP runs the external protocol driver to transfer the file from the BBS to the user. After the transfer is complete, the temporary file is deleted. Uploading using an external protocol is the reverse process. External protocols are not affected by long time delays during network transfers, and are thus inherently more reliable than internal protocols. However, since TCP/IP transfers occur at very high rates, temporary disk space utilization can grow dramatically unless controlled with the ksp-ftp.mb_external configuration parameter. 6.3 Recommendations Of all the internal protocols, Zmodem (downloads) are by far the most reliable (see above). If you are more concerned about reliability than disk space, we recommend replacing all internal protocols by external protocol drivers. If you can't afford the temporary disk space, then internal protocols are the only choice. If you can afford the disk space, we recommend offering both internal and external protocols, since each type offers their Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 28 own particular benefit: internal protocols are faster because they avoid transfering the file twice, but external protocols are more reliable. You may even choose to offer both internal and external versions of the same protocols; if you do, it would be appropriate to prepare a help file or bulletin to explain why to your users. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 29 APPENDIX 1 - HOW TO REACH US The Key Software Products BBS/FAX number (415-364-9847) operates 24 hours a day, 7 days a week. Software at our end automatically determines whether an incoming call is data or FAX and will operate accordingly. If you have access to electronic mail, you can send us a message via any of the following: On COMPUSERVE, send mail to: >Internet:tech.support@ksp.com On Internet, UUCP, or Bitnet, send mail to: tech.support@ksp.com On Fidonet, address mail to "UUCP" at nearest fidonet site which provides a gateway to Internet, such as 1:105/42. 1st line of message: To: tech.support@ksp.com Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 30 APPENDIX 2 - GETTING UPDATES VIA THE INTERNET The main distribution file is KSPFTP??.ZIP, where "??" is the version number. You can retrieve this file via anonymous ftp at "scizzl.scu.edu", directory "ksp". Please note that there is no "e" at the end of "scizzl". This file is also available from the KSP BBS. Copyright (C) 1995-96, Key Software Products. All Rights Reserved Sep 01, 1996 KSP FTP (tm) v3.0 31 APPENDIX 3 - LEGAL STUFF LIMITED WARRANTY This software is provided 'as is' without warranty of any kind, either expressed or implied, including, but not limited to the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Some states do not allow the exclusion of implied warranties, so the above exclusions may not apply to you. This warranty gives you specific legal rights and you may also have other rights which vary from state to state. Key Software Products has taken due care in preparing the documentation and software included in to ascertain their correctness and effectiveness. However, Key Software Products does not warrant that operation of this software will be uninterrupted or error free. In no event shall Key Software Products be liable for incidental or consequential damages in connection with or arising out of the furnishing, performance, or use of this software. LICENSE You MAY use this software on any computer or computers in your possession. The licensed version is registered for use on up to a fixed number of BBS nodes running on multiple machines and/or multiple multi-tasking processes. You MAY copy this software into any machine readable or printed form for backup or modification purposes in support of your use of the software. You MAY distribute the original unmodified, unlicensed version of this software, but you may not charge a fee exceeding $5.00 to cover the cost of duplicating, shipping, and handling. You may NOT distribute a licensed version of this software. You may NOT use, copy, modify, sublicense, assign or transfer this software and its license, or any copy or modification, in whole or in part, except as expressly provided for in this license. Copyright (C) 1995-96, Key Software Products. All Rights Reserved